Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
EmbeddedFrameSpec
Here’s how you should call this method.
ODOObjectSpec* spec = new ODOObjectSpec;
spec->InitODObjectSpec(ev);
container->EmbeddedFrameSpec(..., frame, spec);
Remember that this call might fail if a part up the containment chain does not support it. However, you should always try making this call first because your container knows best how to represent you as an embedded frame, and may be asked to resolve this reference to you later. If the call does fail, you should create an object specifier that describes yourself in some other way such as by persistent object ID.
Token inquiry proc
All instances of this special callback proc are gone. Instead, if a token represents an embedded frame, that token will either be in the format of a standard part token, or will be able to be coerced to one.
GetUserToken/SetUserToken
The old style of usage was based on copy semantics. When you called GetUserToken, you got a copy of your token from the OpenDoc token. If you wanted to add content to that token and have the change reflected in the OpenDoc token, you needed to call SetUserToken.
The new style of usage allows you to manipulate the user token directly. OpenDoc returns a reference to your user token instead of a copy. SetUserToken is gone. You only need use GetUserToken. GetUserToken will return you a reference to an ODDesc which is your token. When you need to add content to your token, you only need to change the contents of the ODDesc. OpenDoc owns the user token and will pass around the reference and will dispose of it when appropriate.
This is similiar to the model in the application world where the OSL passes you a reference to an AEDesc and you fill it in and return. You don’t need to tell the OSL, “Hey, I’ve changed this token now.”.
ODDesc
There are now four public methods on this class that allow you to set and get the raw data and to set and get the descriptor type. You can use these methods to convert from AEDescs to ODDescs and back. In fact, the utility routines ODDescToAEDesc and AEDescToODDesc have been rewritten to use these public methods of ODDesc.
ODOSLToken
One public method was implemented for ODOSLToken, DuplicateODOSLToken. When making a copy of an ODOSLToken, you must use this method.
ODDescToAEDesc/AEDescToODDesc/AEDescChanged
These routines are no longer required in order to use scripting in OpenDoc. However, they are still very useful.
The rules for using these routines were very convoluted and hard to understand.
The new rules are simple: the AEDesc is always copied. The ODDesc is always a reference to an existing ODDesc.
Thus you should always call AEDisposeDesc on a descriptor that you’ve gotten from an ODDesc or that you have put into an ODDesc (assuming that you’re done with it). If an ODDesc has existing content, it will be deleted when AEDescToODDesc is called. AEDescChanged is gone.
Some sample code
Manipulating the user token
for inspection (example: examing the container token in an object accessor or other callback):
